2 * jQuery makeCollapsible
5 * - CC BY 3.0 <http://creativecommons.org/licenses/by/3.0>
6 * - GPL2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.html>
8 * @class jQuery.plugin.makeCollapsible
10 ( function ( $, mw
) {
13 * Handler for a click on a collapsible toggler.
16 * @param {jQuery} $collapsible
17 * @param {string} action The action this function will take ('expand' or 'collapse').
18 * @param {jQuery|null} [$defaultToggle]
19 * @param {Object|undefined} [options]
21 function toggleElement( $collapsible
, action
, $defaultToggle
, options
) {
22 var $collapsibleContent
, $containers
, hookCallback
;
23 options
= options
|| {};
25 // Validate parameters
27 // $collapsible must be an instance of jQuery
28 if ( !$collapsible
.jquery
) {
31 if ( action
!== 'expand' && action
!== 'collapse' ) {
32 // action must be string with 'expand' or 'collapse'
35 if ( $defaultToggle
=== undefined ) {
36 $defaultToggle
= null;
39 // Trigger a custom event to allow callers to hook to the collapsing/expanding,
40 // allowing the module to be testable, and making it possible to
41 // e.g. implement persistence via cookies
42 $collapsible
.trigger( action
=== 'expand' ? 'beforeExpand.mw-collapsible' : 'beforeCollapse.mw-collapsible' );
43 hookCallback = function () {
44 $collapsible
.trigger( action
=== 'expand' ? 'afterExpand.mw-collapsible' : 'afterCollapse.mw-collapsible' );
47 // Handle different kinds of elements
49 if ( !options
.plainMode
&& $collapsible
.is( 'table' ) ) {
51 // If there is a caption, hide all rows; otherwise, only hide body rows
52 if ( $collapsible
.find( '> caption' ).length
) {
53 $containers
= $collapsible
.find( '> * > tr' );
55 $containers
= $collapsible
.find( '> tbody > tr' );
57 if ( $defaultToggle
) {
58 // Exclude table row containing togglelink
59 $containers
= $containers
.not( $defaultToggle
.closest( 'tr' ) );
62 if ( action
=== 'collapse' ) {
63 // Hide all table rows of this table
64 // Slide doesn't work with tables, but fade does as of jQuery 1.1.3
65 // http://stackoverflow.com/questions/467336#920480
66 if ( options
.instantHide
) {
70 $containers
.stop( true, true ).fadeOut().promise().done( hookCallback
);
73 $containers
.stop( true, true ).fadeIn().promise().done( hookCallback
);
76 } else if ( !options
.plainMode
&& ( $collapsible
.is( 'ul' ) || $collapsible
.is( 'ol' ) ) ) {
78 $containers
= $collapsible
.find( '> li' );
79 if ( $defaultToggle
) {
80 // Exclude list-item containing togglelink
81 $containers
= $containers
.not( $defaultToggle
.parent() );
84 if ( action
=== 'collapse' ) {
85 if ( options
.instantHide
) {
89 $containers
.stop( true, true ).slideUp().promise().done( hookCallback
);
92 $containers
.stop( true, true ).slideDown().promise().done( hookCallback
);
96 // Everything else: <div>, <p> etc.
97 $collapsibleContent
= $collapsible
.find( '> .mw-collapsible-content' );
99 // If a collapsible-content is defined, act on it
100 if ( !options
.plainMode
&& $collapsibleContent
.length
) {
101 if ( action
=== 'collapse' ) {
102 if ( options
.instantHide
) {
103 $collapsibleContent
.hide();
106 $collapsibleContent
.slideUp().promise().done( hookCallback
);
109 $collapsibleContent
.slideDown().promise().done( hookCallback
);
112 // Otherwise assume this is a customcollapse with a remote toggle
113 // .. and there is no collapsible-content because the entire element should be toggled
115 if ( action
=== 'collapse' ) {
116 if ( options
.instantHide
) {
120 if ( $collapsible
.is( 'tr' ) || $collapsible
.is( 'td' ) || $collapsible
.is( 'th' ) ) {
121 $collapsible
.fadeOut().promise().done( hookCallback
);
123 $collapsible
.slideUp().promise().done( hookCallback
);
127 if ( $collapsible
.is( 'tr' ) || $collapsible
.is( 'td' ) || $collapsible
.is( 'th' ) ) {
128 $collapsible
.fadeIn().promise().done( hookCallback
);
130 $collapsible
.slideDown().promise().done( hookCallback
);
138 * Handle clicking/keypressing on the collapsible element toggle and other
139 * situations where a collapsible element is toggled (e.g. the initial
140 * toggle for collapsed ones).
143 * @param {jQuery} $toggle the clickable toggle itself
144 * @param {jQuery} $collapsible the collapsible element
145 * @param {jQuery.Event|null} e either the event or null if unavailable
146 * @param {Object|undefined} options
148 function togglingHandler( $toggle
, $collapsible
, e
, options
) {
149 var wasCollapsed
, $textContainer
, collapseText
, expandText
;
150 options
= options
|| {};
154 e
.type
=== 'click' &&
155 e
.target
.nodeName
.toLowerCase() === 'a'
157 // Don't fire if a link was clicked (for premade togglers)
159 } else if ( e
.type
=== 'keypress' && e
.which
!== 13 && e
.which
!== 32 ) {
160 // Only handle keypresses on the "Enter" or "Space" keys
168 // This allows the element to be hidden on initial toggle without fiddling with the class
169 if ( options
.wasCollapsed
!== undefined ) {
170 wasCollapsed
= options
.wasCollapsed
;
172 wasCollapsed
= $collapsible
.hasClass( 'mw-collapsed' );
175 // Toggle the state of the collapsible element (that is, expand or collapse)
176 $collapsible
.toggleClass( 'mw-collapsed', !wasCollapsed
);
178 // Toggle the mw-collapsible-toggle classes, if requested (for default and premade togglers by default)
179 if ( options
.toggleClasses
) {
181 .toggleClass( 'mw-collapsible-toggle-collapsed', !wasCollapsed
)
182 .toggleClass( 'mw-collapsible-toggle-expanded', wasCollapsed
);
185 // Toggle the text ("Show"/"Hide") within elements tagged with mw-collapsible-text
186 if ( options
.toggleText
) {
187 collapseText
= options
.toggleText
.collapseText
;
188 expandText
= options
.toggleText
.expandText
;
190 $textContainer
= $collapsible
.find( '.mw-collapsible-text' );
191 if ( $textContainer
.length
) {
192 $textContainer
.text( wasCollapsed
? collapseText
: expandText
);
196 // And finally toggle the element state itself
197 toggleElement( $collapsible
, wasCollapsed
? 'expand' : 'collapse', $toggle
, options
);
201 * Enable collapsible-functionality on all elements in the collection.
203 * - Will prevent binding twice to the same element.
204 * - Initial state is expanded by default, this can be overridden by adding class
205 * "mw-collapsed" to the "mw-collapsible" element.
206 * - Elements made collapsible have jQuery data "mw-made-collapsible" set to true.
207 * - The inner content is wrapped in a "div.mw-collapsible-content" (except for tables and lists).
209 * @param {Object} [options]
210 * @param {string} [options.collapseText] Text used for the toggler, when clicking it would
211 * collapse the element. Default: the 'data-collapsetext' attribute of the
212 * collapsible element or the content of 'collapsible-collapse' message.
213 * @param {string} [options.expandText] Text used for the toggler, when clicking it would
214 * expand the element. Default: the 'data-expandtext' attribute of the
215 * collapsible element or the content of 'collapsible-expand' message.
216 * @param {boolean} [options.collapsed] Whether to collapse immediately. By default
217 * collapse only if the elements has the 'mw-collapsible' class.
218 * @param {jQuery} [options.$customTogglers] Elements to be used as togglers
219 * for this collapsible element. By default, if the collapsible element
220 * has an id attribute like 'mw-customcollapsible-XXX', elements with a
221 * *class* of 'mw-customtoggle-XXX' are made togglers for it.
222 * @param {boolean} [options.plainMode=false] Whether to use a "plain mode" when making the
223 * element collapsible - that is, hide entire tables and lists (instead
224 * of hiding only all rows but first of tables, and hiding each list
225 * item separately for lists) and don't wrap other elements in
226 * div.mw-collapsible-content. May only be used with custom togglers.
230 $.fn
.makeCollapsible = function ( options
) {
231 options
= options
|| {};
233 this.each( function () {
234 var $collapsible
, collapseText
, expandText
, $caption
, $toggle
, actionHandler
, buildDefaultToggleLink
,
235 $toggleLink
, $firstItem
, collapsibleId
, $customTogglers
, firstval
;
237 // Ensure class "mw-collapsible" is present in case .makeCollapsible()
238 // is called on element(s) that don't have it yet.
239 $collapsible
= $( this ).addClass( 'mw-collapsible' );
241 // Return if it has been enabled already.
242 if ( $collapsible
.data( 'mw-made-collapsible' ) ) {
245 $collapsible
.data( 'mw-made-collapsible', true );
248 // Use custom text or default?
249 collapseText
= options
.collapseText
|| $collapsible
.attr( 'data-collapsetext' ) || mw
.msg( 'collapsible-collapse' );
250 expandText
= options
.expandText
|| $collapsible
.attr( 'data-expandtext' ) || mw
.msg( 'collapsible-expand' );
252 // Default click/keypress handler and toggle link to use when none is present
253 actionHandler = function ( e
, opts
) {
256 toggleText
: { collapseText
: collapseText
, expandText
: expandText
}
258 opts
= $.extend( defaultOpts
, options
, opts
);
259 togglingHandler( $( this ), $collapsible
, e
, opts
);
262 // Default toggle link. Only build it when needed to avoid jQuery memory leaks (event data).
263 buildDefaultToggleLink = function () {
264 return $( '<span class="mw-collapsible-text"></span>' )
265 .text( collapseText
)
266 .wrap( '<span class="mw-collapsible-toggle"></span>' ).parent()
271 .prepend( '<span>[</span>' )
272 .append( '<span>]</span>' )
273 .on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
);
276 // Check if this element has a custom position for the toggle link
277 // (ie. outside the container or deeper inside the tree)
278 if ( options
.$customTogglers
) {
279 $customTogglers
= $( options
.$customTogglers
);
281 collapsibleId
= $collapsible
.attr( 'id' ) || '';
282 if ( collapsibleId
.indexOf( 'mw-customcollapsible-' ) === 0 ) {
283 $customTogglers
= $( '.' + collapsibleId
.replace( 'mw-customcollapsible', 'mw-customtoggle' ) )
284 .addClass( 'mw-customtoggle' );
288 // Add event handlers to custom togglers or create our own ones
289 if ( $customTogglers
&& $customTogglers
.length
) {
290 actionHandler = function ( e
, opts
) {
291 var defaultOpts
= {};
292 opts
= $.extend( defaultOpts
, options
, opts
);
293 togglingHandler( $( this ), $collapsible
, e
, opts
);
296 $toggleLink
= $customTogglers
297 .on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
)
298 .prop( 'tabIndex', 0 );
301 // If this is not a custom case, do the default: wrap the
302 // contents and add the toggle link. Different elements are
303 // treated differently.
305 if ( $collapsible
.is( 'table' ) ) {
307 // If the table has a caption, collapse to the caption
308 // as opposed to the first row
309 $caption
= $collapsible
.find( '> caption' );
310 if ( $caption
.length
) {
311 $toggle
= $caption
.find( '> .mw-collapsible-toggle' );
313 // If there is no toggle link, add it to the end of the caption
314 if ( !$toggle
.length
) {
315 $toggleLink
= buildDefaultToggleLink().appendTo( $caption
);
317 $toggleLink
= $toggle
.on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
)
318 .prop( 'tabIndex', 0 );
321 // The toggle-link will be in one of the cells (td or th) of the first row
322 $firstItem
= $collapsible
.find( 'tr:first th, tr:first td' );
323 $toggle
= $firstItem
.find( '> .mw-collapsible-toggle' );
325 // If theres no toggle link, add it to the last cell
326 if ( !$toggle
.length
) {
327 $toggleLink
= buildDefaultToggleLink().prependTo( $firstItem
.eq( -1 ) );
329 $toggleLink
= $toggle
.on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
)
330 .prop( 'tabIndex', 0 );
334 } else if ( $collapsible
.parent().is( 'li' ) &&
335 $collapsible
.parent().children( '.mw-collapsible' ).length
=== 1 &&
336 $collapsible
.find( '> .mw-collapsible-toggle' ).length
=== 0
338 // special case of one collapsible in <li> tag
339 $toggleLink
= buildDefaultToggleLink();
340 $collapsible
.before( $toggleLink
);
341 } else if ( $collapsible
.is( 'ul' ) || $collapsible
.is( 'ol' ) ) {
342 // The toggle-link will be in the first list-item
343 $firstItem
= $collapsible
.find( 'li:first' );
344 $toggle
= $firstItem
.find( '> .mw-collapsible-toggle' );
346 // If theres no toggle link, add it
347 if ( !$toggle
.length
) {
348 // Make sure the numeral order doesn't get messed up, force the first (soon to be second) item
349 // to be "1". Except if the value-attribute is already used.
350 // If no value was set WebKit returns "", Mozilla returns '-1', others return 0, null or undefined.
351 firstval
= $firstItem
.prop( 'value' );
352 if ( firstval
=== undefined || !firstval
|| firstval
=== '-1' || firstval
=== -1 ) {
353 $firstItem
.prop( 'value', '1' );
355 $toggleLink
= buildDefaultToggleLink();
356 $toggleLink
.wrap( '<li class="mw-collapsible-toggle-li"></li>' ).parent().prependTo( $collapsible
);
358 $toggleLink
= $toggle
.on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
)
359 .prop( 'tabIndex', 0 );
362 } else { // <div>, <p> etc.
364 // The toggle-link will be the first child of the element
365 $toggle
= $collapsible
.find( '> .mw-collapsible-toggle' );
367 // If a direct child .content-wrapper does not exists, create it
368 if ( !$collapsible
.find( '> .mw-collapsible-content' ).length
) {
369 $collapsible
.wrapInner( '<div class="mw-collapsible-content"></div>' );
372 // If theres no toggle link, add it
373 if ( !$toggle
.length
) {
374 $toggleLink
= buildDefaultToggleLink().prependTo( $collapsible
);
376 $toggleLink
= $toggle
.on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
)
377 .prop( 'tabIndex', 0 );
382 $( this ).data( 'mw-collapsible', {
383 collapse: function () {
384 actionHandler
.call( $toggleLink
.get( 0 ), null, { instantHide
: true, wasCollapsed
: false } );
386 expand: function () {
387 actionHandler
.call( $toggleLink
.get( 0 ), null, { instantHide
: true, wasCollapsed
: true } );
389 toggle: function () {
390 actionHandler
.call( $toggleLink
.get( 0 ), null, null );
395 if ( options
.collapsed
|| $collapsible
.hasClass( 'mw-collapsed' ) ) {
396 // One toggler can hook to multiple elements, and one element can have
397 // multiple togglers. This is the sanest way to handle that.
398 actionHandler
.call( $toggleLink
.get( 0 ), null, { instantHide
: true, wasCollapsed
: false } );
404 * Fired after collapsible content has been initialized
406 * This gives an option to modify the collapsible behavior.
408 * @event wikipage_collapsibleContent
410 * @param {jQuery} $content All the elements that have been made collapsible
412 mw
.hook( 'wikipage.collapsibleContent' ).fire( this );
419 * @mixins jQuery.plugin.makeCollapsible
422 }( jQuery
, mediaWiki
) );